Кассовая платёжная ссылка СБП

Главная

Общие положения

Статический QR-код

Динамический QR-код

Кассовая платёжная ссылка

Запрос на регистрацию Кассовой платёжной ссылки СБП

Запрос на активацию Кассовой платёжной ссылки СБП

Запрос деактивации Кассовой платёжной ссылки СБП

Запрос статуса Кассовой платёжной ссылки СБП

Запрос изменения параметров для зарегистрированной Кассовой платёжной ссылки СБП

Запрос на изменение номера терминала (TermNo) для зарегистрированной Кассовой платёжной ссылки СБП/NFC-таблички

Запрос статуса оплаты по Кассовой платёжной ссылке СБП

Нотификация ТСП о финальном статусе оплаты по Кассовой платёжной ссылке СБП

Запрос операций по Кассовой платёжной ссылке СБП

Запрос проведения возврата по успешной оплате по Кассовой платёжной ссылке СБП

Запрос статуса возврата СБП (B2C)

Запрос истории возвратов по определённой транзакции СБП C2B

Нотификация о финальном статусе возврата по Кассовой платёжной ссылке СБП

Привязка счёта / Подписка СБП

Цифровой рубль

Дополнительные методы API

Приложения

Кассовая платёжная ссылка

Кассовая платёжная ссылка СБП

Кассовая платёжная ссылка — это гибридное решение, которое объединяет в себе преимущества статического и динамического QR-кодов, что позволяет многократно использовать неизменяемый QR-код, переопределяя значения части параметров платёжной ссылки.

Благодаря данному решению сам QR-код не меняется, но в то же время сумма оплаты передаётся с кассы, плательщик не может её изменить.

Для совершения оплаты по кассовой платёжной ссылке достаточно один раз распечатать QR-код и разместить его в удобной прикассовой зоне. Сканируя данный QR-код, клиенты могут расплачиваться за разные товары и услуги, при этом самостоятельно не вводя сумму своей покупки перед оплатой.

Для каждой кассы/терминала создается своя кассовая платёжная ссылка.

При каждой активации кассовой платёжной ссылки передаются значения параметров, соответствующие очередной покупке.

1. Запрос на регистрацию Кассовой платёжной ссылки СБП

Данный метод позволяет сгенерировать кассовую платёжную ссылку, которую в дальнейшем ТСП может распечатать в необходимом виде и формате, после чего разместить у кассы для приёма платежей СБП C2B.

Кроме того, метод предоставляет возможность привязывать, полученные от Банка NFC-таблички, к нужным кассам/терминалам.

Метод RegCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «RegCashQRc».
TermNo	String (an-20)	y	Уникальный идентификатор терминала
mediaType	String	o	Тип картинки QR-кода
width	String	o	Ширина картинка QR-кода
height	String	o	Высота картинка QR-кода
redirectUrl	String (ans-1024)	о	Содержит ссылку для автоматического возврата в приложение или на сайт ТСП. Допускаются только символы в кодировке ASCII. Формат должен соответствовать правилам кодировки URL. Если все же требуется использовать в redirectUrl кириллические символы, необходимо перекодировать их в соответствующий ASCII код, используя percent-encoded octets согласно RFC3986
qrcId	String (an-32)	o	Идентификатор QR-кода. Используется в случае, если необходимо привязать заранее зарезервированную в НСПК кассовую платежную ссылку.

b) Примерный формат запроса:


{
    "command":"RegCashQRc",
    "TermNo":"90080567",
    "mediaType":"image/png",
    "width":"600",
    "height":"600",
    "redirectUrl": "https://exampletsp.io/qwertyui"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
content	String	y	Base64-кодированные данные файла изображения QR-кода.
mediaType	String	y	Тип картинки QR-кода.
message	String (ans-1024)	y	Расшифровка кода ответа**.
payload	String (1…999)	y	Платежная ссылка***.
qrcId	String (an-32)	y	Идентификатор QR-кода.
status	String (an-20)	y	Статус кассовой ссылки, полученный из НСПК.

*, ** Таблица возможных кодов ответа приведена в приложении 2.

*** Формат payload может быть двух видов:

d) Примерный формат ответа:

•

200 ОК


{
    "ErrorCode": 0,
    "TermNo": 90080567,
    "content": "iVBORw0KGgoAAAANSUhEUgVXne/ /B2Pwbvw1OqlrAAAAAElFTk…………………………....SuQmCC",
    "mediaType": "image/png",
    "message": "OK",
    "payload": "https://qr.nspk.ru/BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "CREATED"
}

Примечание: текстовые данные передаются в формате urlencoded.

•

400 Bad Request


{
"ErrorCode":"Код ответа",
"message":"Расшифровка кода ответа"
}

2. Запрос на активацию Кассовой платёжной ссылки СБП

Запрос ActivateCashQRc направляется кассой/терминалом ТСП в Банк для активации Кассовой ссылки в целях ожидания оплаты плательщиком. Метод вызывается при каждой оплате.

Метод ActivateCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «ActivateCashQRc».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
qrcId	String (an-32)	y	Идентификатор QR-кода.
amount	Number	y	Сумма платежа в минорных единицах (копейках).
currency	String (ans-3)	o	Код валюты (для рублей должен передаваться «RUB»). Необязательный параметр, при отсутствии его значение принимается = «RUB"
OrderNumber	String (ans-1000)	o	Номер заказа. В параметре должны передаваться только английские буквы и/или арабские цифры, подчеркивание, тире, иначе инициатору будет направлена ошибка.
paymentPurpose	String (ans-140)	o	Назначение платежа.
queryData.notificationUrl	String (ans-512)	o	Полный URL для получения уведомления о финальном статусе оплаты QR-кода Если параметр отсутствует, уведомление не производится.
qrTtl	String (an-1…2)	o	Период использования Кассовой ссылки в минутах. Необязательное поле. Допустимый диапазон: 5-20. Если поле «qrTtl» не передано, то за период использования Кассовой ссылки берется значение по умолчанию — 5 минут.
redirectUrl	String (ans-1024)	o	Содержит ссылку для автоматического возврата в приложение или на сайт ТСП. Допускаются только символы в кодировке ASCII. Формат должен соответствовать правилам кодировки URL. Если требуется использовать в redirectUrl кириллические символы, необходимо перекодировать их в соответствующий ASCII код, используя percent-encoded octets согласно RFC3986.

Блок для внесения дополнительных идентификаторов ТСП

Код ключа		Тип данных	required	Назначение
extJsonParams		Object	o	Блок дополнительных идентификаторов. В блоке можно передать до 10 ключей с необходимыми ТСП значениями.*
	JsonParam1	String (ans-250)	o	Дополнительный идентификатор ТСП
	JsonParam2	String (ans-250)	o	Дополнительный идентификатор ТСП
	...	...	...	...
	JsonParam10	String (ans-250)	o	Дополнительный идентификатор ТСП

* Блок для передачи дополнительных идентификаторов ТСП в ежедневные реестры СБП. Функционал потребует дополнительной настройки реестра по СБП. Для настройки необходимо обратиться в Банк по адресу acquiring@alfabank.ru

b) Примерный формат запроса:


1{
2    "command":"ActivateCashQRc",
3    "TermNo":"90080567",
4    "qrTtl":"5",
5    "amount":"10000",
6    "currency":"RUB",
7    "paymentPurpose":"Назаначение платежа",
8    "OrderNumber":"FYI123456",
9    "redirectUrl": "https://alfabank.ru/sme/payservice/sbp/",
10    "extJsonParams":
11        {
12            "JsonParam1":"Value",
13            "JsonParam2":"Value",
14            "JsonParam3":"Value",
15            "JsonParam4":"Value",
16            "JsonParam5":"Value",
17            "JsonParam6":"Value",
18            "JsonParam7":"Value",
19            "JsonParam8":"Value",
20            "JsonParam9":"Value",
21            "JsonParam10":"Value"
22        },
23   "queryData":
24        {
25            "notificationUrl":"https://sbp-payments",
26        }
27}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
amount	Number	y	Сумма платежа в минорных единицах (копейках).
currency	String (ans-3)	y	Код валюты (для рублей должен передаваться «RUB»).
message	String (ans-1024)	y	Расшифровка кода ответа**.
paramsId	String	y	Идентификатор параметров кассовой платежной ссылки СБП.
paymentPurpose	String (ans-140)	o	Назначение платежа.
payrrn	String (an-12)	y	Референсный идентификатор запроса в системе Банка.
qrcId	String (an-32)	y	Идентификатор QR-кода.
, * Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 ОК


1{
2        "ErrorCode": 0,
3        "TermNo": 90080567,
4        "amount": 10000,
5        "currency": "RUB",
6        "message": "OK",
7        "paramsId": "BP10001UMBREG8GI9AFRVAD7S7GJEK6E",
8        "paymentPurpose": "%u041D%u0430%u0437%u043D%u0430%u0447%u0435%u043D%u0438%u0435 %u043F%u043B%u0430%u0442%u0435%u0436%u0430",
9        "payrrn": "000056251465",
10        "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9"
11    }

Примечание: текстовые данные передаются в формате urlencoded.

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

Примечание:

•
При повторной активации прежние значения параметров Кассовой ссылки СБП заменяются на новые;
•
Если Плательщик отсканирует QR-код активированной Кассовой ссылки СБП и перейдёт в Приложение Плательщика и при этом Кассовая ссылка СБП будет активирована повторно, то после нажатия на кнопку «Оплатить», Плательщику будет сообщено о невозможности совершить оплату;
•
Если в запросе на активацию Кассовой ссылки СБП не будет передан параметр «amount», то ответ вернется с ошибкой — " RQ05019"="Не указана сумма Операции СБП при активации Кассовой ссылки СБП»;
•
Если при активации Кассовой ссылки СБП значение периода использования выходит за пределы допустимого диапазона 1-20 минут, то ответ вернется с ошибкой — «RQ05023"="qrTtl для Кассовой ссылки СБП выходит за допустимый диапазон». На данный момент минимальное значение периода использования Кассовой ссылки СБП — 1 минута, максимальное — 20.
•
Если оплата с использованием Кассовой ссылки СБП имеет финальный статус RJCT (оплата не прошла), то ТСП может повторно активировать Кассовую ссылку СБП, чтобы Плательщик оплатил товары или услуги ТСП.
•
Оплата с использованием Кассовой ссылки СБП невозможна, если:
а) истек период использования активированной Кассовой ссылки СБП;
б) кассовая ссылка СБП не была активирована вовсе или была деактивирована и не активирована вновь;
в) оплата по ней уже происходит, при этом для очередной оплаты она не была активирована вновь.

3. Запрос деактивации Кассовой платёжной ссылки СБП

Запрос DelCashQRc направляется кассой/терминалом ТСП в Банк для досрочной деактивации Кассовой ссылки.

Если Плательщик решил отказаться от покупки и не намерен совершать оплату, когда кассовая ссылка уже была активирована, то она должна быть деактивирована. Деактивацию кассовой ссылки можно произвести после того, как она была активирована, и не была начата процедура оплаты. Деактивация Кассовой ссылки СБП влечет за собой отмену всех дальнейших действий для оплаты по активированной кассовой ссылке.

Если кассовая ссылка была активирована, и по ней происходит оплата, то в ответе на запрос «Деактивация Кассовой ссылки СБП» вернётся ответ «RQ05022"="Невозможно деактивировать Кассовую ссылку СБП».

Метод DelCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «DelCashQRc».
TermNo	String (an-10)	y	Уникальный идентификатор терминала.
qrcId	String(an-32)	y	Идентификатор QR-кода.

b) Примерный формат запроса:


{
    "command":"DelCashQRc",
    "TermNo":"90080567",
    "qrcId":"BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
message	String (ans-140)	y	Расшифровка кода ответа**.
TermNo	String (an-10)	y	Уникальный идентификатор терминала.

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
        "ErrorCode": 0,
        "TermNo": 90080567,
        "message": "%u0417%u0430%u043F%u0440%u043E%u0441 %u043E%u0431%u0440%u0430%u0431%u043E%u0442%u0430%u043D %u0443%u0441%u043F%u0435%u0448%u043D%u043E"
    }

Примечание: текстовые данные передаются в формате urlencoded.

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
    }

4. Запрос статуса Кассовой платёжной ссылки СБП

•
Направляется ТСП в Банк для проверки статуса ранее зарегистрированной кассовой ссылки, например, в целях проверки готовности к активации, или приему платежа.
•
Может быть направлен для проверки статуса после попытки активации, в случае, если на запрос активации не получен ответ от НСПК (или ответ НСПК не содержит «paramsId»).
•
Успешный ответ содержит статус самой Кассовой ссылки, но не операции ее оплаты.

Метод GetCashQRCstatus

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «GetCashQRCstatus».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
qrcId	String (an-32)	y	Идентификатор QR-кода.

b) Примерный формат запроса:


{
    "command": "GetCashQRCstatus",
    "TermNo": "90080567",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
message	String (ans-140)	y	Расшифровка кода ответа**.
status	String	y	Текущий статус кассовой ссылки. В параметре «status» будет возвращаться состояние кассовой ссылки. Варианты состояния кассовой ссылки: — INACTIVATED — ссылка не активирована; — WAITING_PAYMENT — кассовая ссылка СБП активирована и готова к оплате; — IN_PROGRESS — операция по Кассовой ссылке СБП в процессе выполнения.
paramsId	String (an-32)	o	Значение идентификатора параметров для текущей активации кассовой ссылки.
merchantId	String (12)	o	ID мерчанта (ТСТ) в Банке.
, * Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
    "ErrorCode": 0,
    "merchantId":"MB0000009603",
    "message":"Запрос обработан успешно",
    "qrcId":"BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "WAITING_PAYMENT",
    "paramsId": "BP10001UMBREG8GI9AFRVAD7S7GJEK6E"
}

Примечание: текстовые данные передаются в формате urlencoded.

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

5. Запрос изменения параметров для зарегистрированной Кассовой платёжной ссылки СБП

Запрос позволяет изменить следующие параметры Кассовой ссылки СБП:

•
Номер счёта юридического лица — «account»
•
Номер терминала — «TermNo»
•
Торгово-сервисную точку (ТСТ) — «merchantId»
•
Ссылку для автоматического возврата в приложение или на сайт ТСП — «redirectUrl»

Смена счёта юридического лица

Метод ChangeAccForCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «ChangeAccForCashQRc»
TermNo	String (an-20)	y	Уникальный идентификатор терминала, на который Кассовая ссылка СБП зарегистрирована
qrcId	String (an-32)	y	Идентификатор Кассовой ссылки СБП
account	String (n-32)	y	Новый счёт юридического лица

b) Примерный формат запроса для смены номера счёта Кассовой ссылки СБП:


{
    "command":"ChangeAccForCashQRc",
    "TermNo":"90080567",
    "qrcId":"BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "account":"00000000000000001111"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
account	String (an-20)	y	Новый счёт юридического лица
merchantId	String (an-12)	y	Идентификатор ТСТ
message	String (ans-1024)	y	Расшифровка кода ответа**
qrcId	String(an-32)	y	Идентификатор Кассовой ссылки СБП
status	String (an-4)	o	Статус выполнения запроса

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
    "ErrorCode": 0,
    "TermNo": 90080567,
    "account": "00000000000000001111",
    "merchantId": " MA0001111111",
    "message": "OK",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "UPDATED"
}

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

Смена номера терминала/мерчанта для Кассовой ссылки СБП

При успешном выполнении запроса Кассовая ссылка СБП будет перенесена на новый терминал/мерчант

Метод ChangeAccForCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «ChangeAccForCashQRc»
TermNo	String (an-20)	y	Уникальный идентификатор терминала, на который Кассовая ссылка СБП была зарегистрирована
qrcId	String (an-32)	y	Идентификатор QR-кода
account	String (n-32)	y	Счёт юридического лица, установленный для нового терминала
NewTermNo	String (an-20)	y	Новый уникальный идентификатор терминала
NewMerchantId	String (an-12)	y/o	Идентификатор новой ТСТ. Поле обязательно, если терминал, на который переносится Кассовая ссылка СБП, принадлежит новой ТСТ или новому юрлицу

b) Примерный формат запроса для переноса КС на новый терминал, зарегистрированный в рамках одной ТСТ:


{
    "command":"ChangeAccForCashQRc",
    "TermNo":"90080567",
    "account":"00000000000000001111",
    "qrcId":"BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "NewTermNo":"90011111"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
account	String (an-20)	y	Новый счёт юридического лица
merchantId	String (an-12)	y	Идентификатор ТСТ
message	String (ans-1024)	y	Расшифровка кода ответа**
qrcId	String(an-32)	y	Идентификатор Кассовой ссылки СБП
status	String (an-4)	o	Статус выполнения запроса

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
    "ErrorCode": 0,
    "TermNo": 90011111,
    "account": "00000000000000001111",
    "merchantId": " MA0001111111",
    "message": "OK",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "UPDATED"
}

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

e) Примерный формат запроса для переноса КС на новый терминал, зарегистрированный в другой ТСТ или в другом юридическом лице (указать счёт от нового юрлица):


{
    "command": "ChangeAccForCashQRc",
    "TermNo": "90080567",
    "account": "00000000000000002222",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "NewTermNo": "90022222",
    "NewMerchantId": "MA0002222222"
}

f) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
account	String (an-20)	y	Новый счёт юридического лица
merchantId	String (an-12)	y	Идентификатор ТСТ
message	String (ans-1024)	y	Расшифровка кода ответа**
qrcId	String(an-32)	y	Идентификатор Кассовой ссылки СБП
status	String (an-4)	o	Статус выполнения запроса

*, ** Таблица возможных кодов ответа приведена в приложении 2.

g) Примерный формат ответа:

•
200 OK


{
    "ErrorCode": 0,
    "TermNo": 90022222,
    "account": "00000000000000002222",
    "merchantId": " MA0002222222",
    "message": "OK",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "UPDATED"
}

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

h) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
account	String (an-20)	y	Новый счёт юридического лица
merchantId	String (an-12)	y	Идентификатор ТСТ
message	String (ans-1024)	y	Расшифровка кода ответа**
qrcId	String(an-32)	y	Идентификатор Кассовой ссылки СБП
status	String (an-4)	o	Статус выполнения запроса

*, ** Таблица возможных кодов ответа приведена в приложении 2.

Перенос кассовой ссылки на нового мерчанта со старым номером терминала

При успешном выполнении запроса Кассовая ссылка СБП будет перенесена на нового мерчанта вместе со старым терминалом

Метод ChangeAccForCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «ChangeAccForCashQRc»
TermNo	String (an-20)	y	Уникальный идентификатор терминала, на который Кассовая ссылка СБП была зарегистрирована
qrcId	String (an-32)	y	Идентификатор QR-кода
account	String (n-32)	y	Счёт юридического лица, используемый на новом мерчанте
NewMerchantId	String (an-12)	y	Идентификатор новой ТСТ

b) Примерный формат запроса:


{
    "command": "ChangeAccForCashQRc",
    "TermNo": "90080567",
    "account": "00000000000000002222",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "NewMerchantId": "MA0002222222"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
account	String (an-20)	y	Новый счёт юридического лица
merchantId	String (an-12)	y	Идентификатор ТСТ
message	String (ans-1024)	y	Расшифровка кода ответа**
qrcId	String(an-32)	y	Идентификатор Кассовой ссылки СБП
status	String (an-4)	o	Статус выполнения запроса

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
"ErrorCode": 0,
"TermNo": 90080567,
"account": "00000000000000002222",
"merchantId": " MA0002222222",
"message": "OK",
"qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
"status": "UPDATED"
}

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

Смена ссылки для автоматического возврата в приложение или на сайт ТСП

При успешном выполнении запроса будет изменено значение поля «redirectUrl», указанное при первоначальной регистрации Кассовой ссылки СБП методом «RegCashQRc»

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «ChangeAccForCashQRc».
TermNo	String (an-20)	y	Уникальный идентификатор терминала, на который кассовая ссылка/NFC-табличка была зарегистрирована
qrcId	String (an-32)	y	Идентификатор QR-кода
redirectUrl	String (ans-1024)	y	Новая ссылка для автоматического возврата в приложение или на сайт ТСП. Допускаются только символы в кодировке ASCII. Формат должен соответствовать правилам кодировки URL. Если требуется использовать в redirectUrl кириллические символы, необходимо перекодировать их в соответствующий ASCII код, используя percent-encoded octets согласно RFC3986.

b) Примерный формат запроса:


{
    "command": "ChangeAccForCashQRc",
    "TermNo": "90080567",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "redirectUrl": " https://alfabank.ru/sme/payservice/sbp/"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
account	String (an-20)	y	Новый счёт юридического лица
merchantId	String (an-12)	y	Идентификатор ТСТ
message	String (ans-1024)	y	Расшифровка кода ответа**
qrcId	String(an-32)	y	Идентификатор Кассовой ссылки СБП
status	String (an-4)	o	Статус выполнения запроса

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
    "ErrorCode": 0,
    "TermNo": 90080567,
    "account": "00000000000000002222",
    "merchantId": " MA0002222222",
    "message": "OK",
    "qrcId": " BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
    "status": "UPDATED"
}

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

6. Запрос на изменение номера терминала (TermNo) для зарегистрированной Кассовой платёжной ссылки СБП/NFC-таблички

Данный запрос позволяет ТСП произвести смену номера терминала по ранее зарегистрированной Кассовой ссылке СБП на любой другой новый номер терминала. При этом новый номер терминала может принадлежать как той же торговой точке, так и любой другой. Метод также может быть использован и для перепривязки кассовой ссылки на новое ЮЛ, ИП.

Метод ChangeTermNoForCashQRc

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «ChangeTermNoForCashQRc»
TermNo	String (an-20)	y	Уникальный идентификатор терминала
qrcId	String (an-32)	y	Идентификатор кассовой ссылки

b) Примерный формат запроса:


{
    "command": "ChangeTermNoForCashQRc",
    "TermNo": "90080567",
    "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
TermNo	String (an-20)	y	Уникальный идентификатор терминала
message	String (ans-140)	y	Расшифровка кода ответа**
status	String (an-4)	y	Статус выполнения перерегистрации кассовой ссылки на новый терминал (TermNo)

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


{
    "ErrorCode": 0,
    "TermNo": 90080567,
    "message": "OK",
    "status": "UPDATED"
}

•
400 Bad Request


{
    "ErrorCode": "Код ответа",
    "message": "Расшифровка кода ответа"
}

7. Запрос статуса оплаты по Кассовой платёжной ссылке СБП

Запрос статуса GetQRCstatus направляется кассой/терминалом ТСП в Банк для получения статуса Операции оплаты выпущенного ранее QR-кода. В ответе платёжный шлюз Банка возвращает результат обработки Операции оплаты на стороне Банка.

Запрос статуса направляется не ранее, чем через 10 секунд после формирования QR-кода и не чаще чем каждые 3 секунды.

Успешный ответ на запрос статуса можно получить в течении 30 дней после совершения оплаты по данному QR-коду.

В случае, если срок хранения данных истек, то в ответе на запрос вернется:


{
"ErrorCode":999, 
"message":"Неизвестный код проблемы 999RQ05014"
}

Метод GetQRCstatus

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «GetQRCstatus».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
payrrn	String (n-12)	y/o	Референсный идентификатор запроса в системе Банка.
qrcId	String (an-32)	y/o	Идентификатор QR-кода (обязательно, если не передан «payrrn»).
paramsId	String (an-32)	y/o	Идентификатор параметров ссылки СБП (если передан qrcId, то обязателен в случае проверки статуса Кассовой ссылки)
messageID	String (ans-1024)	o	Уникальный идентификатор сообщения, GUID. Только латинские символы!

Примечание: для кассовой платежной ссылки должен быть передан один из параметров: payrrn или qrcId + paramsId. Передавать в запросе qrcId + payrrn нельзя.

b) Примерный формат запроса:

1-й вариант запроса:


{
  "command":"GetQRCstatus",
  "TermNo":"90080567",
  "payrrn":"000056251465",
  "messageID":"message"
}

2-й вариант запроса:


{
  "command":"GetQRCstatus",
  "TermNo":"90080567",
  "qrcId": "AS1R005G9DAOLK5L8S5OPR6HB23HSN0I",
  "paramsId": "BP10001UMBREG8GI9AFRVAD7S7GJEK6E",
  "messageID":"message"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
message	String (ans-1024)	y	Расшифровка кода ответа**.
qrcId	String (an-32)	y	Идентификатор QR-кода.
status	String(an-10)	y	Статус оплаты QR-кода в НСПК* Возможные значения: 1. ACWP — ACCEPTED операция завершена успешно; 2. RJCT — REJECTED операция отклонена; 3. NTST — NOT_STARTED операции по QR коду не существует; 4. RCVD — RECEIVED операция в обработке. При оплате по Цифровом рублю: 1. ENDD — платёж с расчётами в ЦР обработан, но результат выполнения неизвестен (успех или отказ) 2. ACDR — передаётся статус (аналог ACWP при оплате СБП C2B), если есть уведомление от ПлЦР об плате.
trxId	String (an-32)	y	Уникальный идентификатор платежа в НСПК.
trxDT	String (n-14)	y	Дата и время платежа по Гринвичу. Формат — ГГГГММДДччммсс.
payrrn	String (n-12)	o	Референсный идентификатор запроса в системе Банка. Значение возвращается если запрос сделан по «payrrn».
CreditDatePos	String (ans 1-256)	o	Дата операции, установленная Банком Получателя (ГГГГММДД)
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
amount	Number	y	Сумма платежа в минорных единицах (копейках).
currency	String (ans-3)	o	Код валюты (для рублей должен передаваться «RUB»).
Url	String (ans 1-512)	o	Полный URL для получения уведомления ТСП о финальном статусе оплаты QR-кода. Значение параметра, переданного при активации кассовой платежной ссылке в поле «queryData.notificationUrl».
paramsId	String (an-32)	o	Идентификатор активных значений параметров Платежной ссылки СБП. Передается, если оплата происходила по Кассовой ссылке СБП. Значение возвращается если запрос сделан по «payrrn».
payerId	String (ans)	y	Идентификатор плательщика (маскированный номер телефона плательщика).
Kzo	String (ans 1-128)	o	Контрольное Значение Операции СБП. Формируется ОПКЦ СБП. Присутствует при условии, что Операция СБП C2B по запрашиваемому qrcId завершена успешно (параметр «status» =«ACWP»).
messageID	String (ans-1024)	o	Уникальный идентификатор сообщения, GUID. Значение параметра возвращается в случае, если оно указано в запросе.
merchantId	String (12)	o	ID мерчанта (ТСТ) в Банке

*, ** Таблица возможных кодов ответа приведена в приложении 2.

Примечание:

•
Успешно оплаченным считается только QR-код, для которого получен «status» = «ACWP» с идентификатором платежа «trxId» и «ErrorCode» = 0;
•
В случае если получен «status» = «NTST» — означает необходимость повтора запроса до получения одного из финальных статусов «ACWP» или «RJCT»;
•
Получение «status» = «RJCT» означает отказ в оплате данного QR-кода.

d) Примерный формат ответа:

•
200 OK


1{ 
2        "ErrorCode": 0, 
3        "message": "OK", 
4        "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9", 
5        "status": "ACWP", 
6        "trxId": "A30180803159571F0000097B3DA2D4A7", 
7        "trxDT": "20230118080315", 
8        "payrrn": "000056251465", 
9        "CreditDatePos": "20230118", 
10        "TermNo": 90080567, 
11        "amount": 10000, 
12        "currency": "RUB",
13        "Url":"https://sbp-payments",
14        "paramsId": "BP10001UMBREG8GI9AFRVAD7S7GJEK6E", 
15        "payerId": "*********1234", 
16        "kzo": "b02bf0fb819dcc6249f1f6be81da28062236febcb25774a29ebdd770f2a35ba29fa038e459c0845ade1ef2e803729cb7fc40a106852e9f96c72d2fcbe3405efd",
17        "messageID ":"message" 
18        "merchantId": "MB0000009603"
19    }

Примечание:

•

Текстовые данные передаются в формате urlencoded.
•

В поле " trxDT» содержится дата и время транзакции на ПШ Банка в формате ГГГГММДДччммсс.

В случае получения значения trxId = null необходимо повторить запрос. Отсутствие значения означает, что в СБП еще нет успешного перевода с оплатой QR-кода с соответствующим идентификатором.

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

8. Нотификация ТСП о финальном статусе оплаты по Кассовой платёжной ссылке СБП

Запрос отправляется из ПШ Банка во внутреннюю систему ТСП на URL адрес, указанный в параметре «queryData.notificationUrl» при направлении запроса «ActivateCashQRc».

Метод «qrc/notification»

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «qrc/notification»
qrcId	String (an-32)	y	Идентификатор QR-кода.
trxId	String(an-32)	y	Уникальный идентификатор платежа в НСПК.
paramsId	String (an-32)	y	Идентификатор активных значений параметров Платежной ссылки СБП.
status	String(an-10)	y	Статус оплаты QR-кода в НСПК. Возможные значения: — ACWP — ACCEPTED операция завершена успешно; — RJCT — REJECTED операция отклонена.
amount	Number	y	Сумма платежа в минорных единицах (копейках)
timestamp	YYYY-MMDDThh: mm: ss[.SSS] или YYYY-MMDDThh: mm: ss[.SSSZ]	y	Метка времени НСПК по Гринвичу (GMT).
payerId	String (ans)	y	Идентификатор плательщика (маскированный номер телефона плательщика).
kzo	String (ans 1-128)	o	Контрольное Значение Операции СБП. Формируется ОПКЦ СБП. Присутствует при условии, что Операция СБП C2B по запрашиваемому qrcId завершена успешно (параметр "status" ="ACWP").
payrrn	String (n-12)	y	Референсный идентификатор запроса в системе Банка
TermNo	String (an-20)	y	Уникальный идентификатор терминала
CreditDatePos	String (ans 1-256)	o	Дата операции, установленная Банком Получателя в ходе обработки уведомления НСПК

b) Примерный формат запроса:


1{
2    "command":"qrc/notification",
3    "qrcId":"BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
4    "trxId":"A30180803159571F0000097B3DA2D4A7",
5    "paramsId":"BP10001UMBREG8GI9AFRVAD7S7GJEK6E",
6    "status":"ACWP",
7    "amount":"10000",
8    "timestamp":"2023-02-07T08:35:31.102Z",
9    "payerId":"*********1234",
10    "kzo":"d4d45d9db80b29fec2aacbfaf778edc49ff615c13021a2bf5a05f35d8afbcc76f84ceda7598695956c1d5168b1f9cc164961d3ad04aa56544c7cd85ca413ece6",
11    "payrrn":"000056251465",
12    "TermNo":"90080567",
13    "CreditDatePos":"20230207"
14}

c) ВС отвечает http-кодом «200» — успешное получение нотификации, или ошибкой.

В настоящий момент ответ ВС не обрабатывается шлюзом Агента ТСП. Обработка ответов ТСП находится в разработке.

В случае добавления со стороны НСПК дополнительных параметров уведомления, система принимающая их от шлюза Альфа-Банка не должна рассматривать такие неожиданные параметры как ошибочный запрос.

9. Запрос операций по Кассовой платёжной ссылке СБП

•
Запрос позволяет выполнить поиск всех операций оплаты и возвратов, произведенных по определенной кассовой платежной ссылке, с финальным статусом «RJCT» или «ACWP».
•
В ответе платежный шлюз Банка возвращает результат обработки запроса с разбивкой по массивам payments (оплаты) и refunds (возвраты).

Метод «GetCashQrcId»

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «GetCashQrcId».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
qrcId	String (an-32)	y	Идентификатор кассовой ссылки.
dateFrom	date-time	y	Дата начала периода (мск) Формат YYYY-MMDDThh: mm: ss
dateTo	date-time	y	Дата окончания периода (мск) Формат YYYY-MMDDThh: mm: ss

Примечание: Временной диапазон dateFrom — dateTo не должен быть более семи календарных дней. Время в параметре dateFrom должно быть ранее текущего времени запроса не менее, чем на один час.

b) Примерный формат запроса:


{
    "command": "GetCashQrcId",
    "TermNo": "90080567",
    "qrcId": "BS10005FR8SV6EI9931BIQGPSUEG8ELL",
    "dateFrom": "2023-03-12T17:30:09",
    "dateTo": "2023-03-12T23:25:15"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
payments	array	o	Массив платежей:
operationId	string	y	id платежа в НСПК.
status	string (enum)	y	Статус оплаты: — SUCCESS, если финальный статус — ACWP; — REJECTED, если финальный статус — RJCT.
reason	string	o	Описание состояния/причины успешной/неуспешной оплаты.
amount	number	y	Сумма в копейках.
date	date-time	y	Формат YYYY-MM-DDThh: mm: ss
refunds	array	o	Массив возвратов:
refundId	string	y	id возврата в НСПК.
date	date-time	y	Формат YYYY-MM-DDThh: mm: ss
status	string (enum)	y	Статус возврата — SUCCESS, если финальный статус — ACWP; REJECTED, если финальный статус — RJCT.
reason	string	o	Описание причины неуспешного возврата.
amount	number	y	Сумма в копейках.

* Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


1{ 
2    "ErrorCode": 0, 
3    "TermNo": 90080567, 
4    "payments": [ 
5        { 
6            "amount": 10000, 
7            "date": "2024-02-07T14:08:13", 
8            "operationId": "A4038110812414010000020011180902", 
9            "reason": "Запрос обработан успешно", 
10            "status": "SUCCESS" 
11        } 
12    ], 
13    "refunds": [ 
14        { 
15            "amount": 10000, 
16            "date": "2024-02-07T14:19:36", 
17            "reason": "Платёж проведён", 
18            "refundId": "A4038111858413010000020011180902", 
19            "status": "SUCCESS" 
20        } 
21    ] 
22}

Примечание: текстовые данные передаются в формате urlencoded.

•
400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

e) При проверке обязательности заполнения параметров запроса, в случае, если какой-либо параметр не заполнен в ответе вернуться следующие коды ошибок:

ErrorCode	message
"3"	Не передан обязательный параметр dateFrom/dateTo
"16"	Не передан параметр TermNo
"41"	Не передан параметр qrcId
"301"	Превышен временной диапазон dateFrom-dateTo

10. Запрос проведения возврата по успешной оплате по Кассовой платёжной ссылке СБП

Возврат по СБП состоит из 2х последовательных запросов:

•
GetQRCreversalData — проверка возможности проведения возврата;
•
QRCreversal — выполнение непосредственно самого возврата.

В случае если ТСП инициирует выполнение повторных операций СБП B2C по одной и той же операции СБП C2B, то допускается не более 5 (пяти) попыток выполнения повторных операций СБП B2C в течение одного операционного дня.

Возврат в один этап. При направлении запроса «QRCReversal», с заполненным полем messageID будет произведен возврат в один этап без вызова на стороне ТСП метода «GetQRCReversalData»

10.1. Запрос возможности проведения возврата

Запрос GetQRCreversalData направляется ТСП в Банк для проверки возможности возврата по ранее оплаченному QR-коду и получения данных плательщика.

Метод GetQRCreversalData

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «GetQRCreversalData».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
payrrn	String (n-12)	y/o	Референсный идентификатор запроса в системе Банка (обязательно, если не передан «trxId»).
trxId	String (an-32)	y/o	Уникальный идентификатор платежа в НСПК (обязательно, если не передан «payrrn»).
trxDT	String (n-14)	o	Дата и время отменяемого платежа.
amount	Number	o	Сумма возврата в минорных единицах (копейках). Если сумма возврата не передана, то значение будет принято значению суммы оплаты за минусом уже совершенных возвратов.
currency	String (ans-3)	o	Код валюты (для рублей должен передаваться «RUB»). В случае пустого значения валюта будет взята из данных об оплате.
messageID	String (ans-1024)	o	Уникальный идентификатор сообщения, GUID. Только латинские символы!
ReturnRestAmount	Boolean	o	Проверка доступного остатка для совершения возврата. Доступные значения: — true — false

Примечание:

•
Для поиска оригинальной транзакции обязательным является один из параметров: «payrrn» или «trxId»;
•
Терминалы с подключенным сканером и распознаванием QR-кодов могут получить «qrcId», распарсив строку QR-кода с чека оплаты покупки. Формат строки соответствует полю «payload».

b) Примерный формат запроса:


1{
2    "command":"GetQRCreversalData",
3    "TermNo":"90080567",
4    "payrrn":"000056251465",
5    "trxId": "A30180803159571F0000097B3DA2D4A7",
6    "trxDT":"20230416082214",
7    "amount":"10000",
8    "currency":"RUB",
9    "messageID":"f9aa54ff-a615-44b8-aa6c-acab655c89f8",
10    "ReturnRestAmount": true
11}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
message	String (ans-140)	y	Расшифровка кода ответа**.
messageID	String (an-1…50)	y/o	Уникальный идентификатор сообщения, GUID. Только латинские символы!
payerBnkBIC	String (n-9)	y	БИК банка получателя
payerBnkName	String (an-50)	y	Наименование банка получателя
payerId	String (n-13)	y	Идентификатор получателя (маскированный номер телефона получателя).
payerPam	String (ans 1…140)	y	PAM получателя
payrrn	String (n-12)	y	Референсный идентификатор запроса в системе Банка
qrcId	String(an-32)	y	Идентификатор QR-кода.
trxDT	String (n-14)	y	Дата и время платежа в AnyWay (ГГГГММДДччммсс)
trxId	String (an-32)	y	Уникальный идентификатор платежа в НСПК
restAmount	Number (с двумя знаками после точки)	o	Сумма доступного остатка к возврату. Если в запросе передано значение "ReturnRestAmount" : true, то в ответе должен присутствовать параметр RestAmount, содержащий сумму доступного к возврату остатка по операции покупки с TrxId, указанном в запросе.

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


1{
2        "ErrorCode": 0,
3        "TermNo": 90080567,
4        "message": "OK",
5        "messageID":"message",
6        "payerBnkBIC": "044525225",
7        "payerBnkName": "Альфа-Банк",
8        "payerId": "*1234",
9        "payerPam": "ИИИ",
10        "payrrn": "000056251465",
11        "qrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
12        "trxDT": 20230118124954,
13        "trxId": "A3018124954175080000087B3DA2D4A7",
14        "restAmount":"99.87"
15    }

Примечание:

•

Текстовые данные передаются в формате urlencoded;
•

В случае получения "message»: «Получен отказ на запрос возврата. Статус Recall, ErrDebetMerchant: KSM0284 Invalid special condition KSM0284» необходимо проверить счёт ТСП. Он должен быть положительным и без ограничений.
•

400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

10.2. Запрос возврата оплаты

Запрос QRCreversal направляется ТСП в Банк для возврата по ранее произведенной оплате QR. Возврат производится только на счет плательщика, после проверки возможности возврата (метод GetQRCreversalData).

Метод QRCreversal.

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «QRCreversal».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
payrrn	String (n-12)	y/o	Референсный идентификатор запроса в системе Банка (обязательно, если не передан «trxId»).
trxId	String (an-32)	y/o	Уникальный идентификатор платежа в НСПК (обязательно, если не передан «payrrn»).
trxDT	String (n-14)	o	Дата и время отменяемого платежа.
amount	Number	o	Сумма возврата в минорных единицах (копейках). Если сумма возврата не передана, то значение будет принято значению суммы оплаты за минусом уже совершенных возвратов.
currency	String (ans-3)	o	Код валюты (для рублей должен передаваться «RUB»). В случае пустого значения валюта будет взята из данных об оплате.
messageID	String (an-1…50)	y/o	Уникальный идентификатор сообщения, GUID из сообщения «GetQRCreversalData». Обязательно если было указано в запросе GetQRCreversalData*.
queryData.notificationUrl	String (ans-512)	o	Полный URL для получения уведомления о финальном статусе возврата QR-кода. Уведомление не производится в случае пустого значения.
ReturnRestAmount	Boolean	o	Проверка доступного остатка для совершения возврата. Доступные значения: — true — false

Блок для внесения дополнительных идентификаторов ТСП

Код ключа		Тип данных	required	Назначение
extJsonParams		Object	o	Блок дополнительных идентификаторов. В блоке можно передать до 10 ключей с необходимыми ТСП значениями.**
	JsonParam1	String (ans-250)	o	Дополнительный идентификатор ТСП
	JsonParam2	String (ans-250)	o	Дополнительный идентификатор ТСП
	...	...	...	...
	JsonParam10	String (ans-250)	o	Дополнительный идентификатор ТСП

* messageID — необходимо передавать точное значение, которые было указано в ответе на запрос GetQRCreversalData. Если значение изменилось, необходимо повторно создать запрос GetQRCreversalData с указанием messageID и затем использовать полученный GUID при запросе на возврат.

** Блок для передачи дополнительных идентификаторов ТСП в ежедневные реестры СБП. Функционал потребует дополнительной настройки реестра по СБП. Для настройки необходимо обратиться в Банк по адресу acquiring@alfabank.ru

Примечание: Для поиска оригинальной транзакции обязательным является один из параметров: «payrrn» или «trxId».

b) Примерный формат запроса:


1{
2    "command":"QRCreversal",
3    "TermNo":"90080567",
4    "payrrn":"000056251465",
5    "trxId":"A30180803159571F0000097B3DA2D4A7",
6    "trxDT":"20230416082214",
7    "amount":"10000",
8    "currency":"RUB",
9    "messageID":"f9aa54ff-a615-44b8-aa6c-acab655c89f8",
10    "extJsonParams":
11    {
12        "JsonParam1":"Value",
13        "JsonParam2":"Value",
14        "JsonParam3":"Value",
15        "JsonParam4":"Value",
16        "JsonParam5":"Value",
17        "JsonParam6":"Value",
18        "JsonParam7":"Value",
19        "JsonParam8":"Value",
20        "JsonParam9":"Value",
21        "JsonParam10":"Value"
22     },
23    "queryData":
24        {
25        "notificationUrl":"http://sbp-refunds/"
26        },
27    "ReturnRestAmount": true
28 }

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*.
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
amount	Number	y	Сумма платежа в минорных единицах (копейках).
currency	String (ans-3)	y	Код валюты (для рублей должен передаваться «RUB»).
message	String (ans-1024)	y	Расшифровка кода ответа**.
messageID	String (ans-1024)	o	Уникальный идентификатор сообщения, GUID. Только латинские символы!
trxDT	String(n-14)	y	Дата и время операции возврата (ГГГГММДДччммсс).
trxId	String(an-32)	y	Уникальный идентификатор операции возврата в НСПК.
payrrn	String (n-12)	y	Референсный идентификатор запроса в системе Банка.
restAmount	Number (с двумя знаками после точки)	o	Сумма доступного остатка к возврату. Если в запросе передано значение "ReturnRestAmount" : true, то в ответе должен присутствовать параметр RestAmount, содержащий сумму доступного к возврату остатка по операции покупки с TrxId, указанном в запросе.

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•
200 OK


1{
2        "ErrorCode": 0,
3        "TermNo": 90080567,
4        "amount": 10000,
5        "currency": "RUB",
6        "message": "%u0421%u0442%u0430%u0442%u0443%u0441%20%u0432%u044B%u044F%u0441%u043D%u0435%u043D%202024-02-02%2015%3A54%3A39%20%u0432%20%u0441%u0435%u0441%u0441%u0438%u0438%2027556107830.%20Postponed-%3EExecuted",
7        "messageID":"message"
8        "payrrn": "000056251465",
9        "trxDT": 20230614061308,
10        "trxId": "B3018130524291090000167B3DA2D4A7",
11        "restAmount": "99.87"
12    }

Примечание: текстовые данные передаются в формате urlencoded.

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

11. Запрос статуса возврата СБП (B2C)

Метод «GetQRCreversalStatus» необходим ТСП для уточнения статуса операции B2C (метод QRCreversal).

В запросе «GetQRCreversalStatus» обязательно должна быть передана пара параметров:

«payrrn» или «originalTrxId» Один из параметров «payrrn» или «originalTrxId» используется для нахождения исходного платежа C2B.
«trxId» или «messageID». Один из параметров «trxId» или «messageID» используется для нахождения операции возврата B2C, по которому требуется уточнить статус.

Метод «GetQRCreversalStatus»

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «GetQRCreversalStatus».
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
payrrn	String (n-12)	y/o (обязательно, если не передан параметр «originalTrxId»)	Значение параметра «payrrn» из запроса «QRCreversal».
originalTrxId	String (an-32)	y/o (обязательно, если не передан параметр «payrrn»)	Идентификатор исходной Операции СБП C2B.
trxId	String (an-32)	y/o (обязательно, если не передан messageID,)	Уникальный идентификатор операции возврата в НСПК.
messageID	String (ans-1…1024)	y/o (обязательно, если не передан trxId)	Значение параметра «messageID» из запроса «QRCreversal».

b) Примерный формат запроса:


{
  "command":"GetQRCreversalStatus",
  "TermNo":"90080567",
  "payrrn":"000056251465",
  "originalTrxId":"A30180803159571F0000097B3DA2D4A7",
  "trxId":"B3018130524291090000167B3DA2D4A7",
  "messageID":"message"
}

c) Примерный формат ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ошибки*.
TermNo	String (an-20)	y	Уникальный идентификатор терминала.
Url	String (ans 1-512)	o	Полный URL получения уведомления для ТСП — значение параметра, переданного при запросе возврата QRCreversal (queryData.notificationUrl).
amount	Number	y	Сумма Операции СБП в копейках. Целое, положительное число. Валюта операции — рубли РФ.
message	String (ans-1024)	y	Описание результата выполнения запроса**.
messageID	String (ans-1024)	o	Значение параметра «messageID» из запроса «QRCreversal».
originalQrcId	String (an-32)	y	Идентификатор зарегистрированной Платежной ссылки СБП, по которому была выполнена исходная Операция СБП C2B.
originalTrxId	String (an-32)	y	Идентификатор исходной Операции СБП C2B.
payerId	String (an-13)	y	Маскированный номер телефона Клиента-Получателя (Плательщика в исходной Операции C2B, кому делается возврат).
status	String (an-4)	y	Статус операции возврата СБП (B2C): ACWP — ACCEPTED операция завершена успешно; RJCT — REJECTED операция отклонена; NTST — Статус операции неизвестен.
trxDT	String (n-14)	y	Дата и время выполнения Операции СБП B2C по сценарию «Возврат по Операции СБП C2B» (ГГГГММДДччммсс).
trxId	String (an-32)	y	Уникальный идентификатор операции возврата в НСПК.

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа:

•

200 ОК


1{
2    "ErrorCode": 0,
3    "TermNo": 90080567,
4    "amount": 10000,
5    "message": "OK",
6    "messageID": "message"
7    "originalQrcId": "BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
8    "originalTrxId": "A30180803159571F0000097B3DA2D4A7",
9    "payerId": "*********1234",
10    "status": "ACWP",
11    "trxDT": 20230614061308,
12    "trxId": "B3018130524291090000167B3DA2D4A7"
13}

Примечание: текстовые данные передаются в формате urlencoded.

•

400 Bad Request


{
    "ErrorCode":"Код ответа",
    "message":"Расшифровка кода ответа"
}

12. Запрос истории возвратов по определённой транзакции СБП C2B

Запрос позволяет ТСП проверить все совершённые возвраты по определённой транзакции СБП C2B.

В ответе на запрос возвращаются как успешные, так и неуспешные попытки возвратов.

Метод GetQRCreversalHistory

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «GetQRCreversalHistory»
TermNo	String (an-20)	y	Уникальный идентификатор терминала
payrrn	String (n-12)	y	Референсный идентификатор запроса в системе Банка

b) Примерный формат запроса:


{
    "command":"GetQRCreversalHistory",
    "TermNo":"90080567",
    "payrrn":"000000002212"
}

c) Описание параметров ответа:

Код ключа	Тип данных	required	Назначение
ErrorCode	String (an-20)	y	Код ответа*
message	String (ans-1024)	y	Расшифровка кода ответа**
Refunds	Array	y	Массив объектов, содержащих информацию о возвратах по платежу, указанному в payrrn входящего запроса. При отсутствии возвратов, будет возвращён ответ с сообщением – «По данной оплате возвраты не найдены»
refunds.TermNo	String (an-20)	y	Уникальный идентификатор терминала
refunds.amount	Number	y	Сумма Операции СБП B2C (возврат) в копейках. Целое, положительное число. Валюта операции – рубли РФ
refunds.originalQrcId	String (an-32)	y	Идентификатор зарегистрированной Платёжной ссылки СБП (QR-кода), по которому была выполнена исходная Операция оплаты СБП C2B
refunds.originalTrxId	String (an-32)	y	Идентификатор исходной Операции СБП C2B в НСПК
refunds.payerId	String (an-15)	y	Маскированный номер телефона Клиента-Получателя (Плательщика в исходной Операции C2B, кому делается возврат)
refunds.status	String (an-4)	y	Статус операции возврата СБП (B2C): 1. ACWP — ACCEPTED возврат успешно выполнен 2. RJCT — REJECTED возврат отклонён 3. NTST — NOT_STARTED возврат не инициирован (получен успешный ответ на запрос GetQRCreversalData, но не инициирован запрос QRCreversal)
refunds.trxId	String (an-32)	y	Идентификатор Операции возврата СБП B2C по сценарию «Возврат по Операции СБП C2B»
refunds.trxDT	String (n-4)	y	Дата и время выполнения Операции возврата СБП B2C по сценарию «Возврат по Операции СБП C2B». Формат: ГГГГММДДччммсс, UTC +0

*, ** Таблица возможных кодов ответа приведена в приложении 2.

d) Примерный формат ответа «ACWP» и «RJCT»:

•
200 ОК


1{
2        "ErrorCode": 0,
3        "message": "OK",
4        "refunds": [
5            {
6                "TermNo": 90080567,
7                "amount": 10000,
8                "originalQrcId": "AS1F004F30VC6B4A9GRBENS0HI6LGRJM",
9                "originalTrxId": "B51390819586020Z0000120011510503",
10                "payerId": "*********1234",
11                "status": "ACWP",
12                "trxDT": 20250519082345,
13                "trxId": "B51390823097450W0000180011510503"
14            },
15            {
16                "TermNo": 90080567,
17                "amount": 10000,
18                "originalQrcId": "AS1F004F30VC6B4A9GRBENS0HI6LGRJM",
19                "originalTrxId": "B51390819586020Z0000120011510503",
20                "payerId": "*********1234",
21                "status": "RJCT",
22                "trxDT": 20250519083836,
23                "trxId": "A4327120041167130000020011381101"
24            }
25        ]
26    }

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

e) Примерный формат ответа «NTST»:

•
200 ОК


1{
2        "ErrorCode": 0,
3        "message": "OK",
4        "refunds": [
5            {
6                "TermNo": 90080567,
7                "amount": 10000,
8                "originalQrcId": "AS1F004F30VC6B4A9GRBENS0HI6LGRJM",
9                "originalTrxId": "B51390819586020Z0000120011510503",
10                "payerId": "*********1234",
11                "status": "NTST",
12                "trxId": "B51390835362750D0000100011510503"
13            }
14        ]
15    }

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

f) Примерный формат ответа при отсутствии возвратов по транзакции СБП C2B:

•
200 OK


{
        "ErrorCode": 0,
        "message": "%u041F%u043E%20%u0434%u0430%u043D%u043D%u043E%u0439%20%u043E%u043F%u043B%u0430%u0442%u0435%20%u0432%u043E%u0437%u0432%u0440%u0430%u0442%u044B%20%u043D%u0435%20%u043D%u0430%u0439%u0434%u0435%u043D%u044B"
    }

Декодирование значения поля «message» - «По данной оплате возвраты не найдены».

•
400 Bad Request


{
        "ErrorCode":"Код ответа",
        "message":"Расшифровка кода ответа"
    }

13. Нотификация о финальном статусе возврата по Кассовой платёжной ссылке СБП

Запрос отправляется из ПШ Банка во внутреннюю систему ТСП на URL адрес, указанный в параметре «queryData.notificationUrl» при направлении запроса «QRCreversal».

Метод «b2c-refund/notification»

a) Описание параметров запроса:

Код ключа	Тип данных	required	Назначение
command	String (an-1…50)	y	Тип запроса. Константа «b2c-refund/notification»
messageID	String (ans-1024)	o	Уникальный идентификатор сообщения, GUID
TermNo	String (an-20)	y	Уникальный идентификатор терминала
originalQrcId	String (an-32)	y	Идентификатор зарегистрированной Платежной ссылки СБП, по которому была выполнена исходная Операция СБП C2B
originalTrxId	String (an-32)	y	Идентификатор исходной Операции СБП C2B
trxId	String (an-32)	y	Идентификатор Операции СБП B2C по сценарию «Возврат по Операции СБП C2B»
trxDT	String (n-14)	y	Дата и время выполнения Операции СБП B2C по сценарию «Возврат по Операции СБП C2B» (ГГГГММДДччммсс)
status	String (an-4)	y	Финальный статус Операции СБП B2C: "ACWP" — ACCEPTED операция завершена успешно; "RJCT" — REJECTED операция отклонена;
amount	Number	y	Сумма операции в копейках
ErrorCode	String (an-20)	y	Код ответа*
message	String (ans-1024)	y	Расшифровка кода ответа**
payerId	String (an-15)	y	Маскированный номер телефона Клиента-Получателя (Плательщика в исходной Операции C2B, кому делается возврат)
agentRefundRequestId	String (an-32)	y	Уникальный идентификатор запроса, назначаемый ТСП или Агентом ТСП
opkcRefundRequestId	String (an-32)	y	Уникальный идентификатор запроса на возврат, назначенный ОПКЦ СБП

*, ** Таблица возможных кодов ответа приведена в приложении 2.

b) Примерный формат запроса (по успешному возврату):


1{
2"command":"b2c-refund/notification",
3"messageID":" message",
4"TermNo":"90080567",
5"originalQrcId":"BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
6"originalTrxId":"A3018124954175080000087B3DA2D4A7",
7"trxId":"B3018130524291090000167B3DA2D4A7",
8"trxDT":"20230614061308",
9"status":"ACWP",
10"amount":"10000",
11"ErrorCode":"0",
12"message":"OK",
13"payerId":"*********1234",
14"agentRefundRequestId":"00000000000000000182_abcd1994383",
15"opkcRefundRequestId":"BR10000OKEISOIPM8ST8TBLQHIN9R185"
16}

В ответ ожидается:

•
http-код «200» — Успешный ответ (Уведомление получено);
•
http-код «500» — Внутренняя ошибка.

c) Примерный формат запроса (по отклоненному возврату):


1{
2"command":"b2c-refund/notification",
3"TermNo":"90080567",
4"originalQrcId":" BS1R001P1UIGJCFJ9RDQ8974M1I4CJO9",
5"originalTrxId":" A3018124954175080000087B3DA2D4A7",
6"trxId":"A3024113609260070000086B8426B817",
7"trxDT":"20230614061308",
8"status":"RJCT",
9"amount":"10000",
10"ErrorCode":"0",
11"message":"OK",
12"payerId":"*********1234"
13}

В ответ ожидается:

•
http-код «200» — Успешный ответ (Уведомление получено);
•
http-код «500» — Внутренняя ошибка.

d) ВС ТСП отвечает http-кодом «200» — успешное получение нотификации, или ошибкой.

В случае добавления со стороны НСПК дополнительных параметров уведомления, система, принимающая их от шлюза Альфа-Банка, не должна рассматривать такие неожиданные параметры как ошибочный запрос.